<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 (7.0.52) - WebSocket How-To</title><style type="text/css" media="print">
            .noPrint {display: none;}
            td#mainBody {width: 100%;}
        </style><style type="text/css">
            code {background-color:rgb(224,255,255);padding:0 0.1em;}
            code.attributeName, code.propertyName {background-color:transparent;}
        </style><style type="text/css">
            .wrapped-source code { display: block; background-color: transparent; }
            .wrapped-source div { margin: 0 0 0 1.25em; }
            .wrapped-source p { margin: 0 0 0 1.25em; text-indent: -1.25em; }
        </style><style type="text/css">
            p.notice {
                border: 1px solid rgb(255, 0, 0);
                background-color: rgb(238, 238, 238);
                color: rgb(0, 51, 102);
                padding: 0.5em;
                margin: 1em 2em 1em 1em;
            }
        </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="right" alt="
      The Apache Tomcat Servlet/JSP Container
    " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.52, Feb 13 2014</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.2 Javadocs</a></li><li><a href="elapi/index.html">EL 2.2 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.0 Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>WebSocket How-To</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
<ul><li><a href="#Overview">Overview</a></li><li><a href="#Application_development">Application development</a></li><li><a href="#Tomcat_WebSocket_specific_configuration">Tomcat WebSocket specific configuration</a></li><li><a href="#Deprecated_proprietary_API">Deprecated proprietary API</a></li></ul>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>
<p>Tomcat provides support for WebSocket as defined by
   <a href="http://tools.ietf.org/html/rfc6455">RFC 6455</a>.</p>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Application development"><!--()--></a><a name="Application_development"><strong>Application development</strong></a></font></td></tr><tr><td><blockquote>
<p>Tomcat implements the Java WebSocket 1.0 API defined by <a href="http://www.jcp.org/en/jsr/detail?id=356">JSR-356</a>.</p>

<p>There are several example applications that demonstrate how the WebSocket API
   can be used. You will need to look at both the client side <a href="http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/examples/websocket/">
   HTML</a> and the server side <a href="http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/examples/WEB-INF/classes/websocket/">
   code</a>.</p>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Tomcat WebSocket specific configuration"><!--()--></a><a name="Tomcat_WebSocket_specific_configuration"><strong>Tomcat WebSocket specific configuration</strong></a></font></td></tr><tr><td><blockquote>
<p>The JSR-356 Java WebSocket 1.0 implementation is only available when Tomcat
   is running on Java 7 or later.</p>

<p>Tomcat provides a number of Tomcat specific configuration options for
   WebSocket. It is anticipated that these will be absorbed into the WebSocket
   specification over time.</p>

<p>The write timeout used when sending WebSocket messages in blocking mode
   defaults to 20000 milliseconds (20 seconds). This may be changed by setting
   the property <code>org.apache.tomcat.websocket.BLOCKING_SEND_TIMEOUT</code>
   in the user properties collection attached to the WebSocket session. The
   value assigned to this property should be a <code>Long</code> and represents
   the timeout to use in milliseconds. For an infinite timeout, use
   <code>-1</code>.</p>

<p>If the application does not define a <code>MessageHandler.Partial</code> for
   incoming binary messages, any incoming binary messages must be buffered so
   the entire message can be delivered in a single call to the registered
   <code>MessageHandler.Whole</code> for binary messages. The default buffer
   size for binary messages is 8192 bytes. This may be changed for a web
   application by setting the servlet context initialization parameter
   <code>org.apache.tomcat.websocket.binaryBufferSize</code> to the desired
   value in bytes.</p>

<p>If the application does not define a <code>MessageHandler.Partial</code> for
   incoming text messages, any incoming text messages must be buffered so the
   entire message can be delivered in a single call to the registered
   <code>MessageHandler.Whole</code> for text messages. The default buffer size
   for text messages is 8192 bytes. This may be changed for a web application by
   setting the servlet context initialization parameter
   <code>org.apache.tomcat.websocket.textBufferSize</code> to the desired value
   in bytes.</p>

<p>The Java WebSocket specification 1.0 does not permit programmatic deployment
   after the first endpoint has started a WebSocket handshake. By default,
   Tomcat continues to permit additional programmatic deployment. This
   behavior is controlled by the
   <code>org.apache.tomcat.websocket.noAddAfterHandshake</code> servlet context
   initialization parameter. The default may be changed by setting the
   <code>org.apache.tomcat.websocket.STRICT_SPEC_COMPLIANCE</code> system
   property to <code>true</code> but any explicit setting on the servlet context
   will always take priority.</p>

<p>The Java WebSocket 1.0 specification requires that callbacks for
   asynchronous writes are performed on a different thread to the thread that
   initiated the write. Since the container thread pool is not exposed via the
   Servlet API, the WebSocket implementation has to provide its own thread pool.
   This thread pool is controlled by the following servlet context
   initialization parameters:</p>
   <ul>
     <li><code>org.apache.tomcat.websocket.executorCoreSize</code>: The core
         size of the executor thread pool. If not set, the default of 0 (zero)
         is used.</li>
     <li><code>org.apache.tomcat.websocket.executorMaxSize</code>: The maximum
         permitted size of the executor thread pool. If not set, the default of
         10 is used.</li>
     <li><code>org.apache.tomcat.websocket.executorKeepAliveTimeSeconds</code>:
         The maximum time an idle thread will remain in the executor thread pool
         until it is terminated. If not specified, the default of 60 seconds is
         used.</li>
   </ul>

<p>When using the WebSocket client to connect to server endpoints, the timeout
   for IO operations while establishing the connection is controlled by the
   <code>userProperties</code> of the provided
   <code>javax.websocket.ClientEndpointConfig</code>. The property is
   <code>org.apache.tomcat.websocket.IO_TIMEOUT_MS</code> and is the
   timeout as a <code>String</code> in milliseconds. The default is 5000 (5
   seconds).</p>

<p>When using the WebSocket client to connect to secure server endpoints, the
   client SSL configuration is controlled by the <code>userProperties</code>
   of the provided <code>javax.websocket.ClientEndpointConfig</code>. The
   following user properties are supported:</p>
   <ul>
     <li><code>org.apache.tomcat.websocket.SSL_CONTEXT</code></li>
     <li><code>org.apache.tomcat.websocket.SSL_PROTOCOLS</code></li>
     <li><code>org.apache.tomcat.websocket.SSL_TRUSTSTORE</code></li>
     <li><code>org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWD</code></li>
   </ul>
   <p>The default truststore password is <code>changeit</code>.</p>
   <p>If the <code>org.apache.tomcat.websocket.SSL_CONTEXT</code> property is
      set then the <code>org.apache.tomcat.websocket.SSL_TRUSTSTORE</code> and
      <code>org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWD</code> properties
      will be ignored.</p>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deprecated proprietary API"><!--()--></a><a name="Deprecated_proprietary_API"><strong>Deprecated proprietary API</strong></a></font></td></tr><tr><td><blockquote>

<p>Prior to the development of JRS-356, Tomcat provided a proprietary WebSocket
   API. This API has been deprecated in Tomcat 7 and will be removed in Tomcat
   8. There is unlikely to be any further development of this proprietary API
   apart from bug fixes.</p>

<p>For information on this API, please see the Javadoc for the
   <a href="api/index.html?org/apache/catalina/websocket/package-summary.html">
   <code>org.apache.catalina.websocket</code></a> package. The Javadoc
   pages are not included with Tomcat binary distributions. To view them
   locally you would have to download and install "Full documentation"
   distribution, or build it from sources. You can
   also read this on the Apache Tomcat web site. Start with the
   <a href="api/index.html?org/apache/catalina/websocket/WebSocketServlet.html">
   <code>WebSocketServlet</code></a> class.</p>

<p>There are also several example applications that demonstrate how the
   WebSocket API can be used. You'll need to look at both the client side <a href="http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/examples/websocket-deprecated/">
   HTML</a> and the server side <a href="http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/examples/WEB-INF/classes/websocket/tc7/">
   code</a>.</p>
</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
              on improving documentation for Apache Tomcat.<br><br>
              If you have trouble and need help, read
              <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
              and ask your question on the tomcat-users
              <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
              Do not ask such questions here. This is not a Q&amp;A section.<br><br>
              The Apache Comments System is explained <a href="./comments.html">here</a>.
              Comments may be removed by our moderators if they are either
              implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
              var comments_shortname = 'tomcat';
              var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/web-socket-howto.html';
              (function(w, d) {
                  if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
                      d.write('<div id="comments_thread"><\/div>');
                      var s = d.createElement('script');
                      s.type = 'text/javascript';
                      s.async = true;
                      s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
                      (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
                  }
                  else {
                      d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
                  }
              })(window, document);
              //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
        Copyright &copy; 1999-2014, Apache Software Foundation
        </em></font></div></td></tr></table></body></html>